The No-Copy Receive Buffer Structure (IM: OT)

Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

The No-Copy Receive Buffer Structure
You use the no-copy receive buffer structure to specify that you wish to receive data without copying it. You can point to this structure when receiving data with the OTRcvUData function (page 3-105), the OTRcvURequest function (page 3-110), the OTRcvUReply function (page 3-115), the OTRcv function (page 3-134), the OTRcvRequest function (page 3-139), and the OTRcvReply function (page 3-144).

Note
If you are familiar with Streams mblk_t data structures, you can see that the no-copy receive buffer structure is just a slight modification of the mblk_t structure.
You can only use this buffer for data; you cannot use it for the address or options that may be associated with the incoming data. For example, in the case of an incoming TUnitData structure, you can only capture the udata portion, not the addr or opt fields.

WARNING
Under no circumstance write to this data structure. It is read-only. If you write to it, you can crash the system.
The no-copy receive buffer structure is defined by the OTBuffer data type.
struct OTBuffer
{
   void*    fLink;
   void*    fLink2;
   OTBuffer*fNext;
   UInt8*   fData;
   size_t   fLen; 
   void*    fSave;
   UInt8    fBand;
   UInt8    fType;
   UInt8    fPad1;
   UInt8    fFlags;
};

typedef struct OTBuffer OTBuffer;
Field Description

fLink
Reserved.
fLink2
Reserved.
fNext
A pointer to the next OTBuffer structure in the linked chain. By tracing the chain of fNext pointers, you can access all of the data associated with the message.
fData
A pointer to the data portion of this OTBuffer structure.
fLen
The length of data pointed to by the fData field.
fSave
Reserved.
fBand
The band used for the data transmission. It must be a value between 0 and 255.
fType
The type of the data (normally M_DATA, M_PROTO, or M_PCPROTO).
fPad1
Reserved.
fFlags
The flags associated with the data (MSGMARK, MSGDELIM).
IMPORTANT
Once you have copied the data out of the no-copy receive buffer, you need to call the OTReleaseBuffer function as quickly as possible to return the buffer to Open Transport.
In many cases, for performance reasons, drivers pass their actual DMA buffers when they return data. If this is the case, when you do a no-copy receive, you are getting the actual DMA buffers from the driver. If you hold on to the buffer for too long, you may begin to starve the driver for DMA buffers, which adversely affects the performance of the system. It is very important that if you are doing a no-copy receive, you hold onto the buffer for as short a time as possible. If it seems necessary to hold on to the buffer for any length of time, overall performance is better if you instead make a copy of the data and return the buffer to the system.